docs: comprehensive ecosystem documentation for 360Magicians / MBTQ - #4

• Add comprehensive ecosystem docs for workflows, infra, environments, and agent pipelines.
• Add per-project documentation for core 360Magicians/MBTQ repositories.
• Replace the starter OpenAPI with a 360 Magicians lifecycle + inference API definition.

graph TD
A["README.md"] --> B["docs/README.md"] --> C["Ecosystem guides"]
B --> D["Project docs"]
A --> E["openapi/openapi.yaml"] --> F["OpenAPI schemas"]
G["redocly.yaml"] --> E["openapi/openapi.yaml"]

Loading

The following are alternative approaches to this PR:

1. Split into two PRs (Docs vs OpenAPI)

• ➕ Smaller, faster reviews and clearer change history
• ➕ Allows iterating on API spec without re-reviewing docs
• ➖ More coordination overhead
• ➖ Cross-links between docs and spec may temporarily drift

2. Automated docs sync from source repos

• ➕ Reduces manual drift between this repo and upstream documentation
• ➕ Enables scheduled/CI-based updates
• ➖ Requires decisions on sync strategy and conflict handling
• ➖ Can introduce noisy churn in diffs

3. Move to a docs site generator (MkDocs/Docusaurus)

• ➕ Improves navigation/search and scaling ergonomics
• ➕ Better information architecture than long README tables
• ➖ Adds new build/deploy surface area
• ➖ May be premature until content stabilizes

Recommendation: The consolidation approach is a good baseline for discoverability. For maintainability and reviewability, consider follow-ups: keep future OpenAPI changes in separate PRs, and add an automated sync process once upstream docs stabilize.

Documentation (29) +4946 / -94

README.mdRewrite root README as ecosystem docs + OpenAPI entrypoint +51/-1

Rewrite root README as ecosystem docs + OpenAPI entrypoint

• Replaces the starter content with links to the new docs index, ecosystem guides, and project docs, plus basic OpenAPI preview/validation commands.

README.md

README.mdAdd documentation index for ecosystem guides and project docs +117/-0

Add documentation index for ecosystem guides and project docs

• Introduces a docs landing page that catalogs all new guide docs and per-project docs, lists covered repositories, and provides a small API quick reference.

docs/README.md

about.mdAdd 360 Magicians overview and lifecycle/agent roles +66/-0

Add 360 Magicians overview and lifecycle/agent roles

• Adds organization mission/context, repository list, and the IDEA→BUILD→GROW→MANAGED lifecycle with associated Magician agent roles.

docs/about.md

ai-inference.mdDocument inference routing, fallback chains, and latency tiers +240/-0

Document inference routing, fallback chains, and latency tiers

• Adds inference server options, model-prefix routing rules, per-environment/provider routing guidance, fallback ordering, and latency tier definitions.

docs/ai-inference.md

ai-model-manifest.mdAdd canonical AI model registry and deployment/binding matrix +292/-0

Add canonical AI model registry and deployment/binding matrix

• Defines a model registry (providers + HF IDs), an inference-mode matrix (hosted/local/K8s/edge), and common SDK bindings/usage patterns.

docs/ai-model-manifest.md

copilot-bots.mdAdd Copilot/bot configuration and auth access patterns +352/-0

Add Copilot/bot configuration and auth access patterns

• Documents suggested Copilot prompts and CLI commands, authorized bots/apps, and access patterns (GitHub App tokens, OAuth/PAT/JWT).

docs/copilot-bots.md

environments.mdAdd dev/staging/prod model and per-project env-var reference +246/-0

Add dev/staging/prod model and per-project env-var reference

• Defines environment tiers, bootstrap prerequisites/steps, CI promotion expectations, and per-project env var guidance with secrets rules.

docs/environments.md

git-workflow.mdDocument branching strategy and agent GitHub integration +200/-0

Document branching strategy and agent GitHub integration

• Describes lifecycle-aligned branching, agent git flow, GraphQL usage examples, and GitHub webhook events that trigger agent actions.

docs/git-workflow.md

helm.mdAdd Helm deployment guide for MBTQ ecosystem services +292/-0

Add Helm deployment guide for MBTQ ecosystem services

• Documents Helm chart layout for the five main services, environment overrides, and example values for images/replicas/env/ingress.

docs/helm.md

infrastructure.mdAdd ecosystem architecture overview and service map +109/-0

Add ecosystem architecture overview and service map

• Provides a GCP/GKE-centric service map across key domains and references related docs and API usage examples.

docs/infrastructure.md

package-managers.mdDocument per-project runtime/package manager and common commands +316/-0

Document per-project runtime/package manager and common commands

• Maps each project to runtime and package manager (pnpm/npm/Deno/Python) and provides common dev/build/test commands and structure notes.

docs/package-managers.md

pipeline-handoffs.mdAdd end-to-end agent handoff protocol and job DAG reference +447/-0

Add end-to-end agent handoff protocol and job DAG reference

• Documents the pipeline DAG and detailed handoffs with triggers, input/output contracts, and example commands for lifecycle orchestration.

docs/pipeline-handoffs.md

deafauth.mdAdd DeafAuth project docs and lifecycle job catalog +217/-0

Add DeafAuth project docs and lifecycle job catalog

• Introduces DeafAuth as the identity layer, documents bearer token usage, enumerates job IDs per stage, and describes job dependencies.

docs/projects/deafauth.md

fibonrose.mdAdd FibonRose project overview and getting started +58/-0

Add FibonRose project overview and getting started

• Documents FibonRose tech stack, directory structure, and basic pnpm setup steps.

docs/projects/fibonrose.md

mbtq-dev.mdAdd MBTQ.dev project overview and architecture summary +98/-0

Add MBTQ.dev project overview and architecture summary

• Documents MBTQ.dev purpose, key features (including Quinn), stack, repo layout (client/server), and basic run instructions.

docs/projects/mbtq-dev.md

mbtquniverse.mdAdd MBTQUniverse project overview and feature breakdown +172/-0

Add MBTQUniverse project overview and feature breakdown

• Documents MBTQUniverse as the DAO/web3 layer, outlines subsystems (tokenization, governance, staking, metrics), and provides structure/quick start.

docs/projects/mbtquniverse.md

municipal-dao.mdAdd Municipal DAO docs with WebSocket architecture notes +169/-0

Add Municipal DAO docs with WebSocket architecture notes

• Describes real-time voting/notifications, client/server components, env vars, and message type examples for the WebSocket protocol.

docs/projects/municipal-dao.md

pinksync.mdAdd PinkSync overview and API broker positioning +125/-0

Add PinkSync overview and API broker positioning

• Documents PinkSync’s role as accessibility middleware, core services/env vars, and summarizes the larger PinkSync platform and broker endpoints.

docs/projects/pinksync.md

railway-template.mdAdd Railway Next.js template documentation +128/-0

Add Railway Next.js template documentation

• Documents template features, tech stack, project structure, quick start steps, and a representative server-actions pattern example.

docs/projects/railway-template.md

providers.mdAdd provider/vendor catalog and resource summaries +143/-0

Add provider/vendor catalog and resource summaries

• Lists AI providers and platform vendors, classifies components (open-source/proprietary/custom), and summarizes environment resource usage.

docs/providers.md

triggers-webhooks.mdAdd trigger/webhook reference with GitHub App setup +396/-0

Add trigger/webhook reference with GitHub App setup

• Documents trigger layers, GitHub App configuration, token generation, webhook receiver endpoint, and HMAC verification guidance.

docs/triggers-webhooks.md

BuildRepoRequest.yamlDefine BuildRepoRequest schema +18/-0

Define BuildRepoRequest schema

• Adds the request schema for repository creation, including required project name/description and optional tech stack.

openapi/components/schemas/BuildRepoRequest.yaml

CampaignRequest.yamlDefine CampaignRequest schema +13/-0

Define CampaignRequest schema

• Adds the request schema for marketing campaign execution with required brief and optional budget.

openapi/components/schemas/CampaignRequest.yaml

Idea.yamlDefine Idea schema +34/-0

Define Idea schema

• Adds the core Idea object schema including IDs, prompt/title, and optional metadata fields.

openapi/components/schemas/Idea.yaml

IdeaRequest.yamlDefine IdeaRequest schema +13/-0

Define IdeaRequest schema

• Adds the request schema for idea generation with required prompt and optional target audience.

openapi/components/schemas/IdeaRequest.yaml

Job.yamlDefine Job schema for lifecycle job listing/status +40/-0

Define Job schema for lifecycle job listing/status

• Adds a Job object schema including stage, assignment, status, dependencies, and free-form inputs/outputs.

openapi/components/schemas/Job.yaml

ResearchRequest.yamlDefine ResearchRequest schema +13/-0

Define ResearchRequest schema

• Adds the request schema for market research with required topic and optional target audience.

openapi/components/schemas/ResearchRequest.yaml

ValidationReport.yamlDefine ValidationReport schema +36/-0

Define ValidationReport schema

• Adds a validator report schema with validity flag, scores, issues list, and notes.

openapi/components/schemas/ValidationReport.yaml

openapi.yamlRewrite OpenAPI as 360 Magicians API (lifecycle + inference endpoints) +545/-93

Rewrite OpenAPI as 360 Magicians API (lifecycle + inference endpoints)

• Replaces the starter spec with 360 Magicians API metadata/server, DeafAUTH bearer security scheme, lifecycle endpoints (jobs/idea/build/grow/managed), and inference endpoints (LLM/VLM/embed/ASR) including routing-related request/response schemas.

openapi/openapi.yaml

Other (1) +1 / -1

redocly.yamlRename Redocly API entry to 360magicians@v1 +1/-1

Rename Redocly API entry to 360magicians@v1

• Updates the Redocly config identifier while continuing to reference openapi/openapi.yaml as the API root.

redocly.yaml

Description

The OpenAPI description and multiple docs instruct clients to send Authorization: ******, which
does not match the declared scheme: bearer DeafAUTH security scheme and will lead to invalid
requests when copied. The same placeholder also creates effectively blank/misleading auth sections
(e.g., empty headings) in rendered Markdown docs.

Code

openapi/openapi.yaml[R25-31]

+    ## Authentication
+
+    Obtain a token from [DeafAUTH](https://deafauth.mbtq.dev/docs) and pass it as a ******
+
+    ```
+    Authorization: ******
+    ```

Evidence

The OpenAPI description shows Authorization: ****** while the security scheme explicitly declares
bearer auth, so the documented header format is inconsistent and invalid for clients. The same
placeholder appears in multiple docs and even produces an empty heading in the DeafAuth project doc,
indicating the auth documentation is currently broken/misleading.

openapi/openapi.yaml[25-31]
openapi/openapi.yaml[397-403]
docs/README.md[103-114]
docs/projects/deafauth.md[20-28]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Auth examples are currently shown as `******`, which omits the required Bearer token format and renders poorly in Markdown. This conflicts with the OpenAPI `deafauth` security scheme (`scheme: bearer`) and will cause users to copy/paste invalid headers.

## Issue Context
The OpenAPI spec defines DeafAUTH as a bearer token scheme, but the description and docs show `Authorization: ******` instead of `Authorization: Bearer <token>`.

## Fix Focus Areas
- openapi/openapi.yaml[25-31]
- openapi/openapi.yaml[397-403]
- docs/README.md[103-114]
- docs/projects/deafauth.md[20-28]

## Suggested fix
- Replace `******` placeholders with explicit, copy/paste-safe examples:
 - `Authorization: Bearer <DEAFAUTH_TOKEN>`
 - In curl: `-H "Authorization: Bearer $DEAFAUTH_TOKEN"`
- Avoid unescaped asterisks in prose/headings; use `<...>` placeholders or backticks.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

docs/ai-model-manifest.md includes example env vars with real credential prefixes (e.g., sk-...,
AIza...), which can be mistaken for real secrets and may trip simplistic secret-scanning or
compliance checks. These should be replaced with non-secret-pattern placeholders (e.g.,
<OPENAI_API_KEY>).

Code

docs/ai-model-manifest.md[R241-246]

+AI_MODEL_OVERRIDE=llama3        # use local Ollama instead of OpenAI/Gemini
+HF_TOKEN=hf_...                 # HuggingFace token for serverless inference
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_AI_API_KEY=AIza...
+GROQ_API_KEY=gsk_...

Evidence

The .env example explicitly includes multiple well-known API key prefixes that resemble real
credentials, creating avoidable risk/confusion in documentation.

docs/ai-model-manifest.md[239-248]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The docs include env var examples that match common real API key prefixes (`sk-`, `sk-ant-`, `AIza`, `gsk_`). Even though they contain `...`, they can be confused with actual secrets and may trigger basic secret scanners.

## Issue Context
These values appear in a `.env` example in documentation.

## Fix Focus Areas
- docs/ai-model-manifest.md[239-248]

## Suggested fix
Replace secret-looking samples with safer placeholders that do not match real key formats, e.g.:
- `OPENAI_API_KEY=<OPENAI_API_KEY>`
- `ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY>`
- `GOOGLE_AI_API_KEY=<GOOGLE_AI_API_KEY>`
- `GROQ_API_KEY=<GROQ_API_KEY>`
Optionally add a one-liner: "Never paste real keys into docs; use placeholders."

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools